home *** CD-ROM | disk | FTP | other *** search
/ Aminet 5 / Aminet 5 - March 1995.iso / Aminet / util / arc / VEC_3_231.lha / vec3231 / docs / porting.doc < prev    next >
Text File  |  1993-12-06  |  9KB  |  224 lines
  1. Here is the information you need if you are going to port vec to a new
  2. system:
  3.  
  4. DO NOT MODIFY THE EXISTING SOURCE FILES UNLESS IT'S ABSOLUTELY NECESSARY!
  5.  
  6. Create a new header file `system.h' (replace `system' with the name of the
  7. system you are porting vec to) and compile and link main.h, system.h, vec.h
  8. and vdc.h using compiler option, which sets the symbol `MACH_HDR' to value
  9. `"system.h"' (again `system' replaced).
  10.  
  11. system.h may define some or all of these macros:
  12.  
  13. SYSTEM
  14.     A string containing unique identifier for the system you are porting
  15.     to. This string will be appended to the version number. These
  16.     identifiers are already reserved:
  17.  
  18.         "a" - Amiga version
  19.         "g" - generic version
  20.         "m" - MS-DOS version
  21.         "u" - UNIX version
  22.  
  23.     Additional suffixes may be added to system string to identify some
  24.     subset of the generic system type. For example "a030" stands for
  25.     `Amiga with MC68030 or higher CPU'-version. If this macro is not
  26.     defined, the value "g" is used.
  27.  
  28. COPYRSIGN
  29.     A string containing the copyright sign. If the character set of your
  30.     system doesn't contain separate character for the copyright sign or
  31.     many different character sets may be used, then leave this undefined
  32.     and the default value "(c)" will be used.
  33.  
  34. BOLDON
  35.     A string containing the escape sequence which sets the console to
  36.     output boldface. If your console isn't capable to do it or it can't
  37.     be done simply by an escape sequence, leave this undefined or use
  38.     empty string.
  39.  
  40. BOLDOFF
  41.     A string containing an escape sequence for cancelling the effect of
  42.     BOLDON. If BOLDON is undefined or empty string, then leave this also
  43.     undefined or set this to empty string.
  44.  
  45. SMALLUSAGE
  46.     If this macro exists, then the usage displayed when illegal argument
  47.     line is typed will only list the available options. Otherwise it will
  48.     also give a short explanation for each option. This is intented to be
  49.     used when the normal forty-line usage is too big to fit on the
  50.     display.
  51.  
  52. DEFMETHOD
  53.     A character constant to identify the default encoding method. '0',
  54.     '1', '2', '3' or 'u'. If not set, '1' is used.
  55.  
  56. DEFWIDTH
  57.     The default line width - a numeric constant. If not set, the value 80
  58.     is used.
  59.  
  60. DEFWIDTHS
  61.     Same as above, but as a decimal string constant.
  62.  
  63. OK
  64.     Ok return code. Default 0.
  65.  
  66. WARN
  67.     Warning return code (wildcard patterns match nothing). Default 1.
  68.  
  69. ERROR
  70.     Error return code (some file not encoded/decoded properly). Default 2.
  71.  
  72. FAIL
  73.     Failure return code (operation unfinished). Default 3.
  74.  
  75. BUFSIZE
  76.     I/O buffer size in bytes. Two buffers of this size will be allocated.
  77.     The other one will actually be few bytes bigger. Default 32768.
  78.  
  79. VERSTRING
  80.     Unused string to be placed somewhere in the program binary. This is
  81.     for version information finding systems, which try to find some magic
  82.     code from the binary. If not defined, no string will be placed. You
  83.     can use these macros in your string:
  84.  
  85.         ENAME    Encoder name, currently "vec"
  86.         DNAME    Decoder name, currently "vdc"
  87.         UENAME    Upper case ENAME
  88.         UDNAME    Upper case DNAME
  89.         RELEASE    Release number string
  90.         VERSION    Version number string
  91.         VERDATE    Version date string
  92.         SYSTEM    System string explained above
  93.  
  94.     The full version number is `RELEASE "." VERSION SYSTEM'.
  95.  
  96. Besides these optional macros you will need one typedef, which is not
  97. optional:
  98.  
  99. filehandle
  100.     The data type, which represents the lowest level file handle in your
  101.     system. No buffering is required. File functions below should refer
  102.     to filehandles of this type.
  103.  
  104. Then some functions are required. You may emulate these by macros in your
  105. system.h or you may write them as functions to the new source file system.c:
  106.  
  107. void init(void)
  108.     You can put what ever initialization styff you might need in to this
  109.     function. Calling it will be the first thing vec does. If you don't
  110.     need any init function, make it an empty macro.
  111.  
  112. void cleanup(void)
  113.     Like init() but will be called before the program exits.
  114.  
  115. int interrupt(void)
  116.     If programs in your system have to check user interrupt (CTRL-C)
  117.     themselves, then you can put break check into this function. It
  118.     should return 0 if user has not attempted to interrupt the program
  119.     and non-zero if interrupt has been attempted. If you don't need this
  120.     function, make it a macro with value 0.
  121.  
  122. int failedopen(filehandle fh)
  123.     This should return a boolean indicating if the given filehandle is a
  124.     result of failed attempt to open a file.
  125.  
  126. filehandle getstdin(int bin)
  127.     This function should return the filehandle (defined above) referring
  128.     to standard input stream. Parameter is a boolean indicating if the
  129.     stream is wanted in binary mode. If programs in your system have no
  130.     standard input stream, then define this as a macro with a value,
  131.     which forces the failedopen()-function to return true if given to it
  132.     as parameter.
  133.  
  134. filehandle getstdout(int binary)
  135.     Same as above but for standard output.
  136.  
  137. filehandle openread(const char *name, int bin)
  138.     Function to open an existing file with given name for reading. Second
  139.     parameter indicates binary mode. The read pointer should be placed to
  140.     the beginning of the file.
  141.  
  142. filehandle openwrite(const char *name, int bin)
  143.     Create a new file and return a filehandle for writing to it. If file
  144.     with same name existed, it should be discarded.
  145.  
  146. filehandle openappend(const char *name, int bin)
  147.     Open existing file for writing. The write pointer at the end of the
  148.     file.
  149.  
  150. void closefile(filehandle fh)
  151.     Close an open file.
  152.  
  153. int readfile(filehandle fh, unsigned char *buf, int size)
  154.     Read at most <size> bytes from file <fh> to buffer <buf>. Return the
  155.     number of bytes actually read. This is allowed to read less than
  156.     <size> when the file still contains more data, but it is not allowed
  157.     to return zero or less unless the file is exhausted or there has been
  158.     an I/O error. Return value of less than zero is interpreted as an I/O
  159.     error.
  160.  
  161. int writefile(filehandle fh, const unsigned char *buf, int size);
  162.     Write at most <size> bytes from buffer <buf> to file <fh>. Return the
  163.     number of bytes actually written. This is allowed to write less than
  164.     <size>, but it is not allowed to return zero or less unless there has
  165.     been an I/O error.
  166.  
  167. void printerr(const char *string)
  168.     Print a string to standard error stream without buffering.
  169.  
  170. char *basename(const char *name)
  171.     Return pointer to the file name part of the given name, which may
  172.     contain path specification.
  173.  
  174. void setfilemode(const char *name, unsigned char *buf)
  175.     Set the file mode flags of the named file according to information in
  176.     buf. buf[2]&0x0F contains flag type and buf[4] and buf[5] contain the
  177.     actual flags. These are the type values:
  178.  
  179.         0 - No flags
  180.         1 - buf[5] contains the Amiga flag byte
  181.         2 - buf[4]&0x01 is the high and buf[5] the low byte of UNIX
  182.             flags
  183.         3 - MS-DOS flags - details not defined yet
  184.         4 to 15 - not defined yet
  185.  
  186.     Function should try to emulate any type with the flags of the current
  187.     system.
  188.  
  189. void getfilemode(const char *name, const unsigned char *buf, int uuencode)
  190.     If the third parameter is 0, then the file mode flags of the named
  191.     file should be stored to <buf> in any of the formats above. The
  192.     buffer is initialized to zeroes. If the third parameter is non-zero,
  193.     then the flags shoud be converted to unix flags and then written to
  194.     buf[0]...buf[2] as three octal digits. In this case the buffer is
  195.     initialized to "600".
  196.  
  197. char *firstmatch(const char *pattern)
  198. char *nextmatch(void)
  199.     If the program should expand the wildcard patterns in your system
  200.     instead of the shell, then you may provide the expansion mechanism by
  201.     writing these functions. The wildcard pattern is given as parameter
  202.     to both functions.  firstmatch() should return a string pointer to
  203.     the name of the first matching file or NULL if nothing matches().
  204.     The nextmatch is then called to get the subsequent file names until
  205.     it returns NULL. After the nextmatch has returned NULL, the
  206.     firstmatch() may be called again with a different pattern().
  207.     cleanup() function must do the necessary cleaning if the program
  208.     terminates before nextmatch() has returned NULL. If you don't want to
  209.     provide pattern matching mechanism, then define the firstmatch as
  210.     macro with pattern as it's value and nextmatch as macro with value
  211.     NULL.
  212.  
  213. int changedir(const char *directory_name)
  214.     Change the current work directory of the program. Should return zero
  215.     if failed and non-zero otherwise. Only needed when -D option is used.
  216.     If you don't want to implement this, then define it as a macro with
  217.     value 0.
  218.  
  219. See the existing system header and source files for examples.
  220.  
  221. Other sources don't include stdio.h, so if you need it, include it in your
  222. system.h file.
  223.  
  224.